ConfigureDc

Configures distributed clock (DC) options. Distributed clocks allow the synchronization of the slave cycles with the KINGSTAR cycle. It is highly recommended for any motion application to avoid vibrations.

• Master Shift: the reference clock is the clock of the first slave on the EtherCAT network with the DC capability.
• Bus Shift: the reference clock is the master's clock.

Syntax

KsError ConfigureDc(
     BOOL Active,
     BOOL CheckStatus,
     BOOL MasterShift,
     int ReferenceIndex
);

Parameters

Active: TRUE to enable, and FALSE to disable DC synchronization. By default, it is TRUE.

CheckStatus: enables checking of the DC jitter during startup. The devices will go to the operational state (Op) once the synchronization is done. This slows the startup around 15 seconds. By default, it is TRUE.

MasterShift: chooses the shift mode. TRUE: Master Shift. FALSE: Bus Shift. By default, it is FALSE.

Bus Shift means that the EtherCAT slaves follow the master (computer) clock. Master Shift means the slaves and the master follow one of the slaves called "Reference Clock." By default, the Reference Clock will be the first slave on the bus that supports DC.

NOTE:  The slave clocks may be more precise than the computer clock so Master Shift is more stable. However, Master Shift modifies the computer clock's speed which impacts all time stamps done on the computer. This can be a problem if there are other protocols used on the same computer.

ReferenceIndex: selects which device is the reference clock. This parameter is a slave ID, which is the EtherCAT ID of a device. It corresponds to the position of the device in the EtherCAT loop. The ID is zero based and is not affected by aliasing.

NOTE:  ReferenceIndex has not been implemented yet.

Return value

If the function succeeds, it returns errNoError, otherwise an error code. For more information about the error code, see the KsError list.

Remarks

• This function must be called after Create and before Start.
• Disabling DC checks can reduce the startup time by 10 seconds, but no longer guarantee that the synchronization is ready once the system is started. It takes about 1 minute for the clocks to synchronize after the system is in the operational state (Op). We suggest you keep it enabled.
• In Master Shift, the slaves are more stable but the master is less stable. Master Shift should be used only if needed.

Usable EtherCAT states

ecatOffline

Example

//////////////////////////////////////////////////////////////////
//
// This code snippet demonstrates how to use subsystem configuration
// and axis variable APIs to configure the setting before starting
// KINGSTAR subsystem.
//
//////////////////////////////////////////////////////////////////

// Variable declaration
KsError nRet = errNoError;
KsCommandStatus Command = { 0 };
SubsystemStatus Subsystem = { ecatOffline, ecatOffline, 0, 0, 0, {ecatOffline}, {ecatOffline}, {axisOffline} };
double featStatus = -1.0;

// Link to the KINGSTAR subsystem
nRet = Create(0, 0);

// Configure the subsystem settings
// Before enable the features, please check if the corresponding licenses are all enabled
// in the runtime environment.
nRet = ConfigureDc(TRUE, TRUE, TRUE, 0);
nRet = EnableAutoConfig(TRUE);
nRet = EnableAutoRepair(TRUE);
nRet = EnableAutoRestart(TRUE);
nRet = EnableHotConnect(FALSE);
nRet = EnableRedundancy(FALSE);
nRet = EnableServerLog(FALSE);
nRet = SetCycleTime(cycle500);

// Configure the axis variables
// Before enabling variables in the program, you should:
// 1. Read the user manual to check if the variables are available in the device.
// 2. Check if the corresponding variables are put in the PDO list in ESI import tool.
// For further details, see Help System >> KINGSTAR ESI Import Tool >> Tabs >> PDO.
nRet = EnableActualCurrent(TRUE);
nRet = EnableActualTorque(TRUE);
nRet = EnableActualVelocity(TRUE);
nRet = EnableAxisInput(TRUE);
nRet = EnableAxisOutput(FALSE);
nRet = EnableFollowingError(TRUE);
nRet = EnableMaxCurrent(TRUE);
nRet = EnableMaxTorque(TRUE);
nRet = EnableProfilePosition(FALSE);
nRet = EnableSecondEncoder(FALSE);
nRet = EnableSynchronizedControlMode(TRUE);
nRet = EnableTorqueOffset(FALSE);
nRet = EnableTouchProbe(FALSE);
nRet = SetAxisAccessMode(accessPos); // Refer to KsAccessMode page for detailed introduction

// Subsystem setting can be checked anytime after successfully calling Create().
// It is useful to check the feature status when you save the settings in a .kst file
// and start the subsystem via StartFromConfiguration().
nRet = GetFeatureStatus(KsFeature::featureCycleTime, &featStatus);

// Start the EtherCAT network
// You can only configure the setting before starting the subsystem
// If you need to modify the setting, call Stop() first.
Command = WaitForCommand(30, TRUE, Start());

Requirements

See also

Create

Start